openapi: 3.1.0
info:
  contact:
    email: tech.api@hive.app
    name: Hive Support
    url: https://developers.hive.app
  description: >
    The Merchant API v2 provides programmatic access to merchant data

    across all their sales channels.


    This version shifts from sales channel-scoped access to merchant-scoped
    access,

    allowing access to data across all sales channels owned by a single
    merchant.


    The access tokens remain the same as in v1, but now they provide access to
    all sales channels.


    ## Rate Limiting

    All endpoints are rate limited to 100 requests per minute per merchant. The
    following headers are included in every response:

    - `X-Rate-Limit-Used`: The number of requests used in the current minute.

    - `X-Rate-Limit-Max`: The maximum number of requests allowed per minute
    (100).

    If the limit is exceeded, a 429 Too Many Requests response is returned.


    ## Versioning and Deprecation Policy

    v1 of the Merchant API will remain available as long as clients use it, but
    new features and improvements will only be added to v2. We recommend all new
    integrations use v2.


    ## Pagination

    All list endpoints use cursor-based pagination. The
    `pagination.next_page_url` field in the response indicates the next page. If
    `null`, there are no more results. Use the `limit` query parameter to
    control page size. See each endpoint's response schema for details.


    ## Webhooks

    Hive sends webhook notifications to inform you about important events in
    your merchant account. Configure webhook endpoints in your merchant
    dashboard. See the `webhooks` section below for available webhook events and
    their payloads.


    ### Webhook Security

    Hive signs all webhook requests with an `x-hive-signature` header to prevent

    malicious actors from sending invalid requests. This header contains a
    hex-encoded HMAC-SHA256

    digest of the request body, using your API token as the key. Requests
    without this header or

    with invalid signatures should be ignored.


    **Ruby signature validation example**:

    ```ruby

    def request_valid?(req)
      return false if !req.post?
      request_sig = req.get_header("x-hive-signature")
      expected_sig = OpenSSL::HMAC.hexdigest("sha256", ENV["API_TOKEN"], req.body)
      Rack::Utils.secure_compare(request_sig, expected_sig)
    end

    ```


    ### Webhook Reliability

    Webhook URLs should be idempotent as Hive cannot guarantee the order of
    calls

    or retry attempts for the same event. What this means in practice, is that
    you should check the

    timestamp of the object in the payload. Ignore payloads with a timestamp
    older than the last

    update you saved. Only process the webhook if the updated timestamp is newer
    than the one you

    have on file.
  title: Merchant API v2
  version: 2.0.0
servers:
  - description: Production API
    url: https://app.hive.app/merchant_api/v2
  - description: Staging API
    url: https://staging.app.hive.app/merchant_api/v2
security:
  - BearerAuth: []
webhooks:
  order.status_updated:
    summary: Order Status Updated
    description: Triggered when an order status changes
    post:
      operationId: orderStatusUpdatedWebhook
      tags:
        - Orders
        - Webhooks
      parameters:
        - name: x-hive-signature
          in: header
          required: true
          description: >-
            HMAC-SHA256 signature of the request body using your API token as
            the key
          schema:
            type: string
            examples:
              - a1b2c3d4e5f6...
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebhookOrder'
      responses:
        '200':
          description: Webhook received successfully
        '422':
          description: Webhook payload validation failed
  shipment.status_updated:
    summary: Shipment Status Updated
    description: Triggered when a shipment status changes
    post:
      operationId: shipmentStatusUpdatedWebhook
      tags:
        - Shipments
        - Webhooks
      parameters:
        - name: x-hive-signature
          in: header
          required: true
          description: >-
            HMAC-SHA256 signature of the request body using your API token as
            the key
          schema:
            type: string
            examples:
              - a1b2c3d4e5f6...
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebhookShipment'
      responses:
        '200':
          description: Webhook received successfully
  shipment.delivery_status_updated:
    summary: Shipment Delivery Status Updated
    description: Triggered when a shipment delivery status changes
    post:
      operationId: shipmentDeliveryStatusUpdatedWebhook
      tags:
        - Shipments
        - Webhooks
      parameters:
        - name: x-hive-signature
          in: header
          required: true
          description: >-
            HMAC-SHA256 signature of the request body using your API token as
            the key
          schema:
            type: string
            examples:
              - a1b2c3d4e5f6...
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebhookShipment'
      responses:
        '200':
          description: Webhook received successfully
  restocking_shipment.status_updated:
    summary: Restocking Shipment Status Updated
    description: Triggered when a restocking shipment status changes
    post:
      operationId: restockingShipmentStatusUpdatedWebhook
      tags:
        - RestockingShipments
        - Webhooks
      parameters:
        - name: x-hive-signature
          in: header
          required: true
          description: >-
            HMAC-SHA256 signature of the request body using your API token as
            the key
          schema:
            type: string
            examples:
              - a1b2c3d4e5f6...
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebhookRestockingShipment'
      responses:
        '200':
          description: Webhook received successfully
  return.status_updated:
    summary: Return Status Updated
    description: Triggered when a return status changes
    post:
      operationId: returnStatusUpdatedWebhook
      tags:
        - Returns
        - Webhooks
      parameters:
        - name: x-hive-signature
          in: header
          required: true
          description: >-
            HMAC-SHA256 signature of the request body using your API token as
            the key
          schema:
            type: string
            examples:
              - a1b2c3d4e5f6...
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebhookReturn'
      responses:
        '200':
          description: Webhook received successfully
  inventory_transfer_order.status_updated:
    summary: Inventory Transfer Order Status Updated
    description: Triggered when an inventory transfer order status changes
    post:
      operationId: inventoryTransferOrderStatusUpdatedWebhook
      tags:
        - InventoryTransferOrders
        - Webhooks
      parameters:
        - name: x-hive-signature
          in: header
          required: true
          description: >-
            HMAC-SHA256 signature of the request body using your API token as
            the key
          schema:
            type: string
            examples:
              - a1b2c3d4e5f6...
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebhookInventoryTransferOrder'
      responses:
        '200':
          description: Webhook received successfully
tags:
  - description: Operations related to inventory transfer orders
    name: InventoryTransferOrders
  - description: Operations related to orders
    name: Orders
  - description: Operations related to restocking shipments
    name: RestockingShipments
  - description: Operations related to returns
    name: Returns
  - description: Operations related to Stock Keeping Units (SKUs)
    name: SKUs
  - description: Operations related to sales channels
    name: SalesChannels
  - description: Operations related to shipments
    name: Shipments
  - description: Operations related to warehouses
    name: Warehouses
  - description: Webhook event notifications
    name: Webhooks
paths:
  /inventory_transfer_orders:
    get:
      description: >
        Returns all inventory transfer orders for the merchant.


        See the **Pagination** section in the API overview above for details on
        how pagination works.
      operationId: listInventoryTransferOrders
      parameters:
        - $ref: '#/components/parameters/PaginationLimit'
        - $ref: '#/components/parameters/CreatedAtGt'
        - $ref: '#/components/parameters/CreatedAtLt'
        - $ref: '#/components/parameters/CreatedAtGte'
        - $ref: '#/components/parameters/CreatedAtLte'
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  data:
                    items:
                      $ref: '#/components/schemas/InventoryTransferOrder'
                    type: array
                  pagination:
                    $ref: '#/components/schemas/Pagination'
                type: object
          description: A list of inventory transfer orders
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      summary: List inventory transfer orders
      tags:
        - InventoryTransferOrders
    post:
      description: |
        Creates a new inventory transfer order for the merchant.
      operationId: createInventoryTransferOrder
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InventoryTransferOrderCreate'
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InventoryTransferOrder'
          description: Inventory transfer order created successfully
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      summary: Create a new inventory transfer order
      tags:
        - InventoryTransferOrders
  /inventory_transfer_orders/{id}:
    get:
      description: |
        Returns a specific inventory transfer order.
      operationId: getInventoryTransferOrder
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InventoryTransferOrder'
          description: An inventory transfer order
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      summary: Get an inventory transfer order
      tags:
        - InventoryTransferOrders
    parameters:
      - description: Inventory Transfer Order ID
        in: path
        name: id
        required: true
        schema:
          format: int64
          type: integer
    patch:
      description: >
        Partially updates an existing inventory transfer order. Only the
        provided fields will be updated.
      operationId: patchInventoryTransferOrder
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/InventoryTransferOrderPatch'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InventoryTransferOrder'
          description: Inventory transfer order updated successfully
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      summary: Partially update an inventory transfer order
      tags:
        - InventoryTransferOrders
  /inventory_transfer_orders/{id}/cancel:
    parameters:
      - description: Inventory Transfer Order ID
        in: path
        name: id
        required: true
        schema:
          format: int64
          type: integer
    put:
      description: |
        Cancels an existing inventory transfer order.
      operationId: cancelInventoryTransferOrder
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InventoryTransferOrder'
          description: Inventory transfer order cancelled successfully
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      summary: Cancel an inventory transfer order
      tags:
        - InventoryTransferOrders
  /orders:
    get:
      description: >
        Returns all orders across all sales channels belonging to the
        authenticated merchant.


        See the **Pagination** section in the API overview above for details on
        how pagination works.
      operationId: listOrders
      parameters:
        - $ref: '#/components/parameters/SalesChannelIdInFilter'
        - $ref: '#/components/parameters/PaginationLimit'
        - $ref: '#/components/parameters/CreatedAtGt'
        - $ref: '#/components/parameters/CreatedAtLt'
        - $ref: '#/components/parameters/CreatedAtGte'
        - $ref: '#/components/parameters/CreatedAtLte'
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  data:
                    items:
                      $ref: '#/components/schemas/Order'
                    type: array
                  pagination:
                    $ref: '#/components/schemas/Pagination'
                type: object
          description: A list of orders
          headers:
            X-Rate-Limit-Used:
              description: The number of requests used in the current minute.
              schema:
                type: integer
              examples:
                default:
                  value: 10
            X-Rate-Limit-Max:
              description: The maximum number of requests allowed per minute (100).
              schema:
                type: integer
              examples:
                default:
                  value: 100
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      summary: List orders
      tags:
        - Orders
    post:
      description: >
        Creates a new order for a specific sales channel within the merchant's
        organization.
      operationId: createOrder
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrderCreate'
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'
          description: Order created successfully
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      summary: Create a new order
      tags:
        - Orders
  /orders/{id}:
    get:
      description: |
        Returns a specific order.
      operationId: getOrder
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'
          description: An order
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      summary: Get an order
      tags:
        - Orders
    parameters:
      - description: Order ID
        in: path
        name: id
        required: true
        schema:
          format: int64
          type: integer
    patch:
      description: >
        Partially updates an existing order. Only the provided fields will be
        updated.


        **Note:** The unique identifiers `merchant_order_id` and
        `sales_channel_id` cannot be

        updated and will be ignored if provided in the request body.
      operationId: patchOrder
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrderPatch'
            examples:
              updateCarrierPreference:
                summary: Update order carrier preference
                value:
                  carrier_preference: PostNL
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'
              examples:
                updated:
                  summary: Order updated successfully
                  value:
                    id: 123456
                    items:
                      - merchant_item_id: '1'
                        price_per_unit_in_cents: 1500
                        quantity: 2
                        sku_code: SKU-001
                        sku_id: 1001
                    merchant_order_id: ORD-1001
                    sales_channel_id: 10
                    shipping_address:
                      city: Berlin
                      country_code: DE
                      first_name: Anna
                      line1: Alexanderplatz 1
                      postal_code: '10178'
                    fulfillment_status: shipped
                    financial_status: paid
                    created_at: '2023-10-01T12:00:00Z'
                    currency: EUR
                    payment_method: credit_card
                    tags:
                      - priority
                      - gift
                    total_price_in_cents: 3000
                    total_tax_in_cents: 570
                    total_net_revenue_in_cents: 2430
                    total_net_refunds_in_cents: 0
                    total_tax_refunds_in_cents: 0
                    custom_metadata:
                      gift_message: Happy Birthday!
                    customer_order_number: CUST-ORD-2023-01
                    carrier_preference: PostNL
                    updated_at: '2023-10-01T15:30:00Z'
          description: Order updated successfully
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      summary: Partially update an order
      tags:
        - Orders
  /orders/{id}/cancel:
    parameters:
      - description: Order ID
        in: path
        name: id
        required: true
        schema:
          format: int64
          type: integer
    put:
      description: |
        Cancels an existing order.
      operationId: cancelOrder
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'
          description: Order cancelled successfully
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      summary: Cancel an order
      tags:
        - Orders
  /restocking_shipments:
    get:
      description: >
        Returns all restocking shipments for the merchant.


        See the **Pagination** section in the API overview above for details on
        how pagination works.
      operationId: listRestockingShipments
      parameters:
        - $ref: '#/components/parameters/CreatedAtGt'
        - $ref: '#/components/parameters/CreatedAtLt'
        - $ref: '#/components/parameters/CreatedAtGte'
        - $ref: '#/components/parameters/CreatedAtLte'
        - $ref: '#/components/parameters/PaginationLimit'
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  data:
                    items:
                      $ref: '#/components/schemas/RestockingShipment'
                    type: array
                  pagination:
                    $ref: '#/components/schemas/Pagination'
                type: object
          description: A list of restocking shipments
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      summary: List restocking shipments
      tags:
        - RestockingShipments
    post:
      description: |
        Creates a new restocking shipment for the merchant.
      operationId: createRestockingShipment
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RestockingShipmentCreate'
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RestockingShipment'
          description: Restocking shipment created successfully
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      summary: Create a restocking shipment
      tags:
        - RestockingShipments
  /restocking_shipments/{id}:
    get:
      description: |
        Returns a specific restocking shipment.
      operationId: getRestockingShipment
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RestockingShipment'
          description: A restocking shipment
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      summary: Get a restocking shipment
      tags:
        - RestockingShipments
    parameters:
      - description: Restocking Shipment ID
        in: path
        name: id
        required: true
        schema:
          format: int64
          type: integer
    put:
      description: >
        Updates an existing restocking shipment. Only allowed if the shipment
        status is "shipped" or "created". This operation replaces the entire
        resource.
      operationId: updateRestockingShipment
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RestockingShipmentUpdate'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RestockingShipment'
          description: Restocking shipment updated successfully
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      summary: >-
        Update a restocking shipment (replace only, allowed if status is
        "shipped" or "created")
      tags:
        - RestockingShipments
  /restocking_shipments/{id}/cancel:
    parameters:
      - description: Restocking Shipment ID
        in: path
        name: id
        required: true
        schema:
          format: int64
          type: integer
    put:
      description: |
        Cancels an existing restocking shipment.
      operationId: cancelRestockingShipment
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
          description: Restocking shipment cancelled successfully
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      summary: Cancel a restocking shipment
      tags:
        - RestockingShipments
  /returns:
    get:
      description: >
        Returns all returns across all sales channels belonging to the
        authenticated merchant.


        See the **Pagination** section in the API overview above for details on
        how pagination works.
      operationId: listReturns
      parameters:
        - $ref: '#/components/parameters/SalesChannelIdInFilter'
        - $ref: '#/components/parameters/CreatedAtGt'
        - $ref: '#/components/parameters/CreatedAtLt'
        - $ref: '#/components/parameters/CreatedAtGte'
        - $ref: '#/components/parameters/CreatedAtLte'
        - $ref: '#/components/parameters/PaginationLimit'
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  data:
                    items:
                      $ref: '#/components/schemas/Return'
                    type: array
                  pagination:
                    $ref: '#/components/schemas/Pagination'
                type: object
          description: A list of returns
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      summary: List returns
      tags:
        - Returns
  /returns/{id}:
    get:
      description: |
        Returns a specific return.
      operationId: getReturn
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Return'
          description: A return
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      summary: Get a return
      tags:
        - Returns
    parameters:
      - description: Return ID
        in: path
        name: id
        required: true
        schema:
          format: int64
          type: integer
  /sales_channels:
    get:
      description: >
        Returns all sales channels available to the merchant.


        See the **Pagination** section in the API overview above for details on
        how pagination works.
      operationId: listSalesChannels
      parameters:
        - $ref: '#/components/parameters/PaginationLimit'
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  data:
                    items:
                      $ref: '#/components/schemas/SalesChannel'
                    type: array
                  pagination:
                    $ref: '#/components/schemas/Pagination'
                type: object
          description: A list of sales channels
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      summary: List sales channels
      tags:
        - SalesChannels
  /shipments:
    get:
      description: >
        Returns all shipments across all sales channels belonging to the
        authenticated merchant.


        See the **Pagination** section in the API overview above for details on
        how pagination works.
      operationId: listShipments
      parameters:
        - $ref: '#/components/parameters/PaginationLimit'
        - $ref: '#/components/parameters/OrderIdInFilter'
        - $ref: '#/components/parameters/MerchantOrderIdInFilter'
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  data:
                    items:
                      $ref: '#/components/schemas/Shipment'
                    type: array
                  pagination:
                    $ref: '#/components/schemas/Pagination'
                type: object
          description: A list of shipments
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      summary: List shipments
      tags:
        - Shipments
  /skus:
    get:
      description: >
        Returns all SKUs belonging to the authenticated merchant.


        See the **Pagination** section in the API overview above for details on
        how pagination works.
      operationId: listSkus
      parameters:
        - $ref: '#/components/parameters/PaginationLimit'
        - $ref: '#/components/parameters/CreatedAtGt'
        - $ref: '#/components/parameters/CreatedAtLt'
        - $ref: '#/components/parameters/CreatedAtGte'
        - $ref: '#/components/parameters/CreatedAtLte'
        - $ref: '#/components/parameters/SkuCodeInFilter'
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  data:
                    items:
                      $ref: '#/components/schemas/Sku'
                    type: array
                  pagination:
                    $ref: '#/components/schemas/Pagination'
                type: object
          description: A list of SKUs
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      summary: List SKUs
      tags:
        - SKUs
    post:
      description: |
        Creates a new SKU for the merchant. SKUs must have a unique SKU code.
        New SKUs are marked as "verified" and fulfilled_by "hive".
      operationId: createSku
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SkuCreate'
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Sku'
          description: SKU created successfully
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      summary: Create a new SKU
      tags:
        - SKUs
  /skus/{id}:
    delete:
      description: |
        Deletes an existing SKU.
      operationId: deleteSku
      responses:
        '204':
          description: SKU deleted successfully
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      summary: Delete a SKU
      tags:
        - SKUs
    get:
      description: |
        Returns a specific SKU by its ID.
      operationId: getSku
      responses:
        '200':
          description: A SKU
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Sku'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      summary: Get a SKU by ID
      tags:
        - SKUs
    parameters:
      - description: SKU ID
        in: path
        name: id
        required: true
        schema:
          format: int64
          type: integer
    patch:
      description: >
        Partially updates an existing SKU. Only the provided fields will be
        updated.
      operationId: patchSku
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SkuPatch'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Sku'
          description: SKU updated successfully
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      summary: Partially update a SKU
      tags:
        - SKUs
  /warehouses:
    get:
      description: >
        Returns all warehouses available to the merchant.


        See the **Pagination** section in the API overview above for details on
        how pagination works.
      operationId: listWarehouses
      parameters:
        - $ref: '#/components/parameters/PaginationLimit'
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  data:
                    items:
                      $ref: '#/components/schemas/Warehouse'
                    type: array
                  pagination:
                    $ref: '#/components/schemas/Pagination'
                type: object
          description: A list of warehouses
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      summary: List warehouses
      tags:
        - Warehouses
  /orders/by_merchant_order_id:
    get:
      summary: Get an order by merchant order ID and sales channel
      description: >-
        Returns a specific order using the merchant's order ID and sales channel
        ID.
      operationId: getOrderByMerchantId
      parameters:
        - name: sales_channel_id
          in: query
          required: true
          schema:
            format: int64
            type: integer
        - name: merchant_order_id
          in: query
          required: true
          schema:
            type: string
      responses:
        '200':
          description: An order
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      tags:
        - Orders
    patch:
      summary: Partially update an order by merchant order ID and sales channel
      description: >
        Partially updates an order using the merchant's order ID and sales
        channel ID.


        **Note:** The unique identifiers `merchant_order_id` and
        `sales_channel_id` cannot be

        updated and will be ignored if provided in the request body.
      operationId: patchOrderByMerchantId
      parameters:
        - name: sales_channel_id
          in: query
          required: true
          schema:
            format: int64
            type: integer
        - name: merchant_order_id
          in: query
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrderPatch'
      responses:
        '200':
          description: Order updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      tags:
        - Orders
  /skus/by_sku_code:
    get:
      summary: Get a SKU by merchant SKU code
      description: Returns a specific SKU using the merchant's SKU code.
      operationId: getSkuByCode
      parameters:
        - name: sku_code
          in: query
          required: true
          schema:
            type: string
            minLength: 1
      responses:
        '200':
          description: A SKU
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Sku'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      tags:
        - SKUs
    patch:
      summary: Partially update a SKU by merchant SKU code
      description: Partially updates a SKU using the merchant's SKU code.
      operationId: patchSkuByCode
      parameters:
        - name: sku_code
          in: query
          required: true
          schema:
            type: string
            minLength: 1
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SkuPatch'
      responses:
        '200':
          description: SKU updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Sku'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      tags:
        - SKUs
    delete:
      summary: Delete a SKU by merchant SKU code
      description: Deletes a SKU using the merchant's SKU code.
      operationId: deleteSkuByCode
      parameters:
        - name: sku_code
          in: query
          required: true
          schema:
            type: string
            minLength: 1
      responses:
        '204':
          description: SKU deleted successfully
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      tags:
        - SKUs
components:
  parameters:
    CreatedAtGt:
      description: Filter results created after this date (ISO 8601 format)
      in: query
      name: created_at[gt]
      required: false
      schema:
        format: date-time
        type: string
    CreatedAtGte:
      description: Filter results created on or after this date (ISO 8601 format)
      in: query
      name: created_at[gte]
      required: false
      schema:
        format: date-time
        type: string
    CreatedAtLt:
      description: Filter results created before this date (ISO 8601 format)
      in: query
      name: created_at[lt]
      required: false
      schema:
        format: date-time
        type: string
    CreatedAtLte:
      description: Filter results created on or before this date (ISO 8601 format)
      in: query
      name: created_at[lte]
      required: false
      schema:
        format: date-time
        type: string
    MerchantOrderIdInFilter:
      description: Filter results by one or more merchant order IDs
      explode: false
      in: query
      name: merchant_order_id[in]
      required: false
      schema:
        items:
          type: string
        type: array
    OrderIdInFilter:
      description: Filter results by one or more Hive order IDs
      explode: false
      in: query
      name: order_id[in]
      required: false
      schema:
        items:
          format: int64
          type: integer
        type: array
    PaginationLimit:
      description: Number of items to return per page (for pagination)
      in: query
      name: limit
      required: false
      schema:
        default: 20
        maximum: 100
        minimum: 1
        type: integer
    SalesChannelIdInFilter:
      description: Filter results by one or more sales channel ID
      explode: false
      in: query
      name: sales_channel_id[in]
      required: false
      schema:
        items:
          format: int64
          type: integer
        type: array
    SkuCodeInFilter:
      description: Filter results by one or more merchant SKU codes
      explode: false
      in: query
      name: sku_code[in]
      required: false
      schema:
        items:
          type: string
          minLength: 1
        type: array
  responses:
    BadRequest:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            openapi_validation:
              summary: OpenAPI validation error
              value:
                success: false
                title: Bad Request Body
                status: 400
                errors:
                  - message: value at `/data/name` is not a string
                    pointer: /data/name
                    code: string
                  - message: 'number at `/data/numberOfLegs` is less than: 2'
                    pointer: /data/numberOfLegs
                    code: minimum
            general_bad_request:
              summary: General bad request
              value:
                success: false
                title: Bad Request
                status: 400
                errors:
                  - bad request
      description: >-
        Bad request - the request couldn't be understood or contains invalid
        parameters
    Conflict:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            validation_conflict:
              summary: Validation conflict (legacy format)
              value:
                success: false
                errors:
                  merchant_order_id:
                    - a record with this data already exists
            general_conflict:
              summary: General conflict
              value:
                success: false
                title: Conflict
                status: 409
                errors:
                  - A record with this data already exists
      description: Conflict - the request conflicts with the current state of the resource
    Forbidden:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            default:
              value:
                success: false
                title: Forbidden
                status: 403
                errors:
                  - Access denied
      description: >-
        Access denied - the authenticated user doesn't have permission to access
        the requested resource
    NotFound:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            default:
              value:
                success: false
                title: Not Found
                status: 404
                errors:
                  - Record not found
      description: Resource not found - the requested resource doesn't exist
    Unauthorized:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            default:
              value:
                success: false
                title: Unauthorized
                status: 401
                errors:
                  - Authentication required
      description: >-
        Authentication required - the request lacks valid authentication
        credentials
    UnprocessableEntity:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            validation_errors:
              summary: Field validation errors (legacy format)
              value:
                success: false
                errors:
                  name:
                    - can't be blank
                  sku_code:
                    - can't be blank
            detailed_validation:
              summary: Detailed validation errors
              value:
                success: false
                title: Validation Error
                status: 422
                errors:
                  - message: Name can't be blank
                    code: blank
                    pointer: /name
                  - message: SKU code can't be blank
                    code: blank
                    pointer: /sku_code
      description: Validation error - the request contains invalid data
    TooManyRequests:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            default:
              value:
                success: false
                title: Too Many Requests
                status: 429
                errors:
                  - Rate limit exceeded
      description: Too many requests - rate limit exceeded
  schemas:
    Address:
      properties:
        city:
          description: City name
          type: string
          minLength: 1
        company:
          description: Company name
          type:
            - string
            - 'null'
        country_code:
          $ref: '#/components/schemas/CountryCode'
        email:
          description: Email address
          type:
            - string
            - 'null'
          format: email
        first_name:
          description: >-
            Customer's first name - required if `last_name` and `full_name` are
            omitted
          type:
            - string
            - 'null'
          minLength: 1
        full_name:
          description: >-
            Customer's full name - required if `first_name` and `last_name` are
            omitted
          type:
            - string
            - 'null'
          minLength: 1
        last_name:
          description: >-
            Customer's last name - required if `first_name` and `full_name` are
            omitted
          type:
            - string
            - 'null'
          minLength: 1
        line1:
          description: Customer's address line 1
          type: string
          minLength: 1
        line2:
          description: Customer's address line 2
          type:
            - string
            - 'null'
        parcel_point_id:
          description: >-
            Parcel point ID - see [Sendcloud service
            points](https://api.sendcloud.dev/docs/sendcloud-public-api/branches/v2/service-points)
          type:
            - string
            - 'null'
        phone:
          description: Customer's phone number
          type:
            - string
            - 'null'
        postal_code:
          description: Customer's postal code
          type: string
          minLength: 1
        province_or_state_code:
          description: >
            State or province code. For US addresses, this should be the
            2-letter state code (e.g., CA, NY, TX).

            For other countries, this should be the appropriate
            province/state/region code.

            Examples: CA (California), NY (New York), ON (Ontario), BE (Berlin)
          type:
            - string
            - 'null'
      required:
        - city
        - country_code
        - line1
        - postal_code
      anyOf:
        - required:
            - first_name
        - required:
            - last_name
        - required:
            - full_name
      type: object
      examples:
        - city: Berlin
          company: Hive GmbH
          country_code: DE
          email: customer@example.com
          first_name: Anna
          last_name: Musterfrau
          line1: Alexanderplatz 1
          line2: Apt 5
          phone: '+491234567890'
          postal_code: '10178'
          province_or_state_code: BE
          full_name: Anna Musterfrau
          parcel_point_id: SC-12345
    Error:
      description: >
        Error response schema that supports multiple error formats:

        1. Validation errors with field-specific messages (legacy format for
        backward compatibility)

        2. General errors with messages and optional metadata

        3. OpenAPI validation errors with detailed information
      properties:
        errors:
          description: >
            Error information. Can be:

            - Object with field names as keys and error arrays as values (for
            validation errors)

            - Array of error objects with message, code, and optional metadata

            - Array of strings (for simple error messages)
          oneOf:
            - type: object
              description: Field-specific validation errors (legacy format)
              additionalProperties:
                type: array
                items:
                  type: string
            - type: array
              description: List of error objects or simple error messages
              items:
                oneOf:
                  - type: string
                    description: Simple error message
                  - type: object
                    description: Detailed error object
                    properties:
                      message:
                        description: Human-readable error message
                        type: string
                      code:
                        description: Machine-readable error code
                        type: string
                      pointer:
                        description: >-
                          JSON pointer to the location of the error (for OpenAPI
                          validation errors)
                        type: string
                    required:
                      - message
        success:
          description: Indicates if the request was successful
          type: boolean
        title:
          description: A brief, human-readable message about the error
          type: string
        status:
          description: HTTP status code
          type: integer
          format: int32
      required:
        - errors
      type: object
    InventoryTransferOrder:
      properties:
        completed_at:
          description: When the inventory transfer order was completed
          readOnly: true
          type:
            - string
            - 'null'
          format: date-time
        created_at:
          description: When the inventory transfer order was created
          format: date-time
          type: string
          readOnly: true
        destination_id:
          description: The ID of the destination warehouse
          format: int64
          type: integer
        documents:
          description: List of documents associated with the inventory transfer order
          items:
            $ref: '#/components/schemas/InventoryTransferOrderDocument'
          type: array
        id:
          description: Hive's unique identifier for this inventory transfer order
          format: int64
          type: integer
          readOnly: true
        items:
          description: List of items in the inventory transfer order
          items:
            $ref: '#/components/schemas/InventoryTransferOrderItem'
          type: array
        order:
          $ref: '#/components/schemas/InventoryTransferOrderReference'
        order_notes:
          description: Notes for the inventory transfer order
          type:
            - string
            - 'null'
        origin_id:
          description: The ID of the origin warehouse
          format: int64
          type: integer
        restocking_shipments:
          description: >-
            List of restocking shipments associated with the inventory transfer
            order
          items:
            $ref: '#/components/schemas/InventoryTransferOrderRestockingShipment'
          type: array
        shipments:
          description: List of shipments associated with the inventory transfer order
          items:
            $ref: '#/components/schemas/InventoryTransferOrderShipment'
          type: array
        status:
          $ref: '#/components/schemas/InventoryTransferOrderStatus'
        updated_at:
          description: When the inventory transfer order was last updated
          format: date-time
          type: string
          readOnly: true
      required:
        - created_at
        - destination_id
        - documents
        - id
        - items
        - order
        - origin_id
        - restocking_shipments
        - shipments
        - status
        - updated_at
      type: object
      examples:
        - id: 297
          status: processing
          created_at: '2025-06-05T15:15:12.256+02:00'
          completed_at: null
          order:
            id: 1195780
            status: processing
          origin_id: 4
          destination_id: 2
          order_notes: ''
          documents: []
          restocking_shipments:
            - id: 1916
              status: created
              estimated_arrival_date: null
              tracking_code: null
              tracking_url: null
              items: []
          shipments:
            - id: 684202
              status: in_packing
              issues: []
              items: []
              restocking_shipment:
                id: 1916
                status: created
                estimated_arrival_date: null
                tracking_code: null
                tracking_url: null
                items: []
          items:
            - id: 427
              quantity: 1
              sku_id: 161820
              sku_code: 41827199320226-empty
              inventory_batch:
                id: 123456
                name: Batch-001
                expiry_date: '2025-06-05'
          updated_at: '2025-06-05T16:20:15.300+02:00'
    InventoryTransferOrderCreate:
      properties:
        destination_id:
          description: The ID of the destination warehouse
          format: int64
          type: integer
        items:
          description: List of items for the inventory transfer order
          items:
            properties:
              inventory_batch_id:
                description: The ID of the inventory batch
                anyOf:
                  - type: integer
                    format: int64
                  - type: 'null'
              quantity:
                description: The quantity of this item to transfer
                format: int32
                type: integer
                minimum: 1
              sku_code:
                description: >-
                  The merchant's SKU identifier - required if `sku_id` is not
                  provided
                type: string
              sku_id:
                description: Hive's SKU identifier - required if `sku_code` is not provided
                format: int64
                type: integer
            required:
              - quantity
            anyOf:
              - required:
                  - sku_id
              - required:
                  - sku_code
            type: object
          type: array
        order_notes:
          description: Notes for the inventory transfer order
          type: string
        origin_id:
          description: The ID of the origin warehouse
          format: int64
          type: integer
      required:
        - destination_id
        - items
        - origin_id
      type: object
      examples:
        - origin_id: 39
          destination_id: 38
          order_notes: ''
          items:
            - inventory_batch_id: null
              quantity: 100
              sku_id: 586004
    InventoryTransferOrderDocument:
      properties:
        id:
          description: Document ID
          format: int64
          type: integer
        name:
          description: Document name
          type:
            - string
            - 'null'
        url:
          description: Document URL
          type: string
      required:
        - id
        - name
        - url
      type: object
      examples:
        - id: 12345
          name: transfer_receipt.pdf
          url: >-
            https://docs.hive.app/transfers/12345/receipt.pdf?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIA4%&X-Amz-Date=20230525T083045Z&X-Amz-Expires=900&X-Amz-SignedHeaders=host&X-Amz-Signature=d8e3
    InventoryTransferOrderInventoryBatch:
      type:
        - object
        - 'null'
      properties:
        expiry_date:
          description: Expiration date of the batch
          type:
            - string
            - 'null'
          format: date
        id:
          description: Batch ID
          format: int64
          type: integer
        name:
          description: Batch name
          type: string
      required:
        - id
        - name
      examples:
        - id: 123456
          name: Batch-001
          expiry_date: '2025-06-05'
    InventoryTransferOrderItem:
      properties:
        id:
          description: Hive's unique identifier for this item
          format: int64
          type: integer
          readOnly: true
        inventory_batch:
          $ref: '#/components/schemas/InventoryTransferOrderInventoryBatch'
        quantity:
          description: The quantity of this item to transfer
          format: int32
          type: integer
          minimum: 1
        sku_code:
          description: The merchant's SKU identifier - required if `sku_id` is not provided
          type: string
        sku_id:
          description: Hive's SKU identifier - required if `sku_code` is not provided
          format: int64
          type: integer
      required:
        - id
        - quantity
        - sku_code
        - sku_id
      type: object
      examples:
        - id: 427
          quantity: 1
          sku_id: 161820
          sku_code: 41827199320226-empty
          inventory_batch:
            id: 123456
            name: Batch-001
            expiry_date: '2025-06-05'
    InventoryTransferOrderPatch:
      properties:
        destination_id:
          description: The ID of the destination warehouse
          format: int64
          type: integer
        order_notes:
          description: Notes for the inventory transfer order
          type: string
        origin_id:
          description: The ID of the origin warehouse
          format: int64
          type: integer
      type: object
      examples:
        - order_notes: Updated notes
          destination_id: 3
    InventoryTransferOrderReference:
      type:
        - object
        - 'null'
      properties:
        id:
          description: Order ID
          format: int64
          type:
            - integer
            - 'null'
        status:
          description: Order status
          type:
            - string
            - 'null'
      examples:
        - id: 1195780
          status: processing
    InventoryTransferOrderRestockingShipment:
      properties:
        estimated_arrival_date:
          description: Estimated arrival date
          type:
            - string
            - 'null'
          format: date
        id:
          description: Restocking shipment ID
          format: int64
          type: integer
        items:
          description: Items in the restocking shipment
          items:
            $ref: '#/components/schemas/RestockingShipmentItem'
          type: array
        status:
          description: Restocking shipment status
          type: string
        tracking_code:
          description: Tracking code
          type:
            - string
            - 'null'
        tracking_url:
          description: Tracking URL
          type:
            - string
            - 'null'
      required:
        - id
        - items
        - status
      type: object
      examples:
        - id: 1916
          status: created
          estimated_arrival_date: null
          tracking_code: null
          tracking_url: null
          items: []
    InventoryTransferOrderShipment:
      properties:
        id:
          description: Shipment ID
          format: int64
          type: integer
        issues:
          description: Issues with the shipment
          items:
            type: object
          type: array
        items:
          description: Items in the shipment
          items:
            $ref: '#/components/schemas/InventoryTransferOrderShipmentItem'
          type: array
        restocking_shipment:
          $ref: '#/components/schemas/InventoryTransferOrderRestockingShipment'
        status:
          description: Shipment status
          type: string
      required:
        - id
        - issues
        - items
        - status
      type: object
      examples:
        - id: 684202
          status: in_packing
          issues: []
          items: []
    InventoryTransferOrderShipmentItem:
      properties:
        id:
          description: Shipment item ID
          format: int64
          type: integer
        quantity:
          description: Quantity in the shipment
          format: int32
          type: integer
          minimum: 1
        sku_code:
          description: The merchant's SKU code
          type: string
        sku_id:
          description: The SKU ID
          format: int64
          type: integer
      required:
        - id
        - quantity
        - sku_code
        - sku_id
      type: object
      examples:
        - id: 451386
          quantity: 1
          sku_id: 161820
          sku_code: 41827199320226-empty
    Order:
      properties:
        carrier_preference:
          description: The preferred carrier to use for delivering this order
          type:
            - string
            - 'null'
        created_at:
          description: When the order was created. Will default to current time if omitted.
          format: date-time
          type: string
          readOnly: true
        currency:
          $ref: '#/components/schemas/CurrencyCode'
        custom_metadata:
          additionalProperties: true
          description: A JSON object with custom metadata
          type:
            - object
            - 'null'
        customer_order_number:
          description: >-
            The order number which your customer sees. In case this is not the
            same as `merchant_order_id`.
          type:
            - string
            - 'null'
        external_created_at:
          description: >-
            When the order was originally created/placed by the customer. This
            can be different from created_at when doing bulk imports or when
            there's a delay between order placement and API submission.
          format: date-time
          type:
            - string
            - 'null'
        financial_status:
          $ref: '#/components/schemas/OrderFinancialStatus'
        id:
          description: Hive's unique identifier for this order
          format: int64
          type: integer
          readOnly: true
        items:
          description: List of items in the order (see OrderItem)
          items:
            $ref: '#/components/schemas/OrderItem'
          type: array
        merchant_order_id:
          description: >-
            An ID that uniquely identifies this order within the sales channel.
            Must be unique per sales channel.
          type: string
        payment_method:
          description: The payment method used for this order
          type:
            - string
            - 'null'
        sales_channel_id:
          description: The ID of the sales channel this order belongs to
          format: int64
          type: integer
        shipping_address:
          $ref: '#/components/schemas/Address'
        fulfillment_status:
          $ref: '#/components/schemas/OrderFulfillmentStatus'
        tags:
          description: String tags for this order
          type:
            - array
            - 'null'
          items:
            type: string
        total_net_refunds_in_cents:
          description: Net refunds in cents (total refunded minus taxes)
          format: int32
          type: integer
          minimum: 0
        total_net_revenue_in_cents:
          description: Net revenue in cents (amount paid minus taxes)
          format: int32
          type: integer
          minimum: 0
        total_price_in_cents:
          description: Total price paid in cents
          format: int32
          type: integer
          minimum: 0
        total_tax_in_cents:
          description: Total tax paid in cents
          format: int32
          type: integer
          minimum: 0
        total_tax_refunds_in_cents:
          description: Total tax in the refunded amount in cents
          format: int32
          type: integer
          minimum: 0
        updated_at:
          description: When the order was last updated
          format: date-time
          type: string
          readOnly: true
      required:
        - id
        - items
        - merchant_order_id
        - sales_channel_id
        - shipping_address
        - carrier_preference
        - fulfillment_status
        - financial_status
        - total_price_in_cents
        - currency
        - created_at
        - total_net_refunds_in_cents
        - total_net_revenue_in_cents
        - total_tax_in_cents
        - total_tax_refunds_in_cents
        - updated_at
      type: object
      examples:
        - id: 123456
          items:
            - merchant_item_id: '1'
              price_per_unit_in_cents: 1500
              quantity: 2
              sku_code: SKU-001
              sku_id: 1001
          merchant_order_id: ORD-1001
          sales_channel_id: 10
          shipping_address:
            city: Berlin
            country_code: DE
            first_name: Anna
            line1: Alexanderplatz 1
            postal_code: '10178'
          fulfillment_status: waiting_for_picking
          financial_status: paid
          created_at: '2023-10-01T12:00:00Z'
          currency: EUR
          payment_method: credit_card
          tags:
            - priority
            - gift
          total_price_in_cents: 3000
          total_tax_in_cents: 570
          total_net_revenue_in_cents: 2430
          total_net_refunds_in_cents: 0
          total_tax_refunds_in_cents: 0
          custom_metadata:
            gift_message: Happy Birthday!
          customer_order_number: CUST-ORD-2023-01
          carrier_preference: DHL
          external_created_at: '2023-10-01T10:30:00Z'
          updated_at: '2023-10-01T14:30:00Z'
    OrderCreate:
      properties:
        carrier_preference:
          description: The preferred carrier to use for delivering this order
          type:
            - string
            - 'null'
        currency:
          $ref: '#/components/schemas/CurrencyCode'
        custom_metadata:
          additionalProperties: true
          description: A JSON object with custom metadata
          type:
            - object
            - 'null'
        customer_order_number:
          description: >-
            The order number which your customer sees. In case this is not the
            same as `merchant_order_id`.
          type:
            - string
            - 'null'
        external_created_at:
          description: >-
            When the order was originally created/placed by the customer. This
            can be different from created_at when doing bulk imports or when
            there's a delay between order placement and API submission.
          format: date-time
          type:
            - string
            - 'null'
        financial_status:
          $ref: '#/components/schemas/OrderFinancialStatus'
        items:
          description: List of items in the order (see OrderItem)
          items:
            $ref: '#/components/schemas/OrderItem'
          type: array
          minItems: 1
        merchant_order_id:
          description: >-
            An ID that uniquely identifies this order within the sales channel.
            Must be unique per sales channel.
          type: string
          minLength: 1
        payment_method:
          description: The payment method used for this order
          type:
            - string
            - 'null'
        sales_channel_id:
          description: The ID of the sales channel this order belongs to
          format: int64
          type: integer
        shipping_address:
          $ref: '#/components/schemas/Address'
        tags:
          description: String tags for this order
          type:
            - array
            - 'null'
          items:
            type: string
        total_net_refunds_in_cents:
          description: Net refunds in cents (total refunded minus taxes)
          format: int32
          type: integer
          minimum: 0
        total_net_revenue_in_cents:
          description: Net revenue in cents (amount paid minus taxes)
          format: int32
          type: integer
          minimum: 0
        total_price_in_cents:
          description: Total price paid in cents
          format: int32
          type: integer
          minimum: 0
        total_tax_in_cents:
          description: Total tax paid in cents
          format: int32
          type: integer
          minimum: 0
        total_tax_refunds_in_cents:
          description: Total tax in the refunded amount in cents
          format: int32
          type: integer
          minimum: 0
      required:
        - items
        - merchant_order_id
        - sales_channel_id
        - shipping_address
      type: object
      examples:
        - items:
            - merchant_item_id: '1'
              price_per_unit_in_cents: 1500
              quantity: 2
              sku_code: SKU-001
              sku_id: 1001
          merchant_order_id: ORD-1001
          sales_channel_id: 10
          shipping_address:
            city: Berlin
            country_code: DE
            first_name: Anna
            line1: Alexanderplatz 1
            postal_code: '10178'
          currency: EUR
          payment_method: credit_card
          tags:
            - priority
            - gift
          total_price_in_cents: 3000
          total_tax_in_cents: 570
          total_net_revenue_in_cents: 2430
          total_net_refunds_in_cents: 0
          total_tax_refunds_in_cents: 0
          custom_metadata:
            gift_message: Happy Birthday!
          customer_order_number: CUST-ORD-2023-01
          carrier_preference: DHL
          external_created_at: '2023-10-01T10:30:00Z'
    OrderFinancialStatus:
      description: |
        Financial status of this order. Possible values:
        - failed: Payment failed
        - paid: Payment completed successfully
        - pending: Payment is pending
        - refunded: Payment has been refunded
      enum:
        - failed
        - paid
        - pending
        - refunded
      type: string
    OrderItem:
      properties:
        merchant_item_id:
          description: >-
            Identifier for the line item. Needs to be unique among the line
            items of the order.
          type: string
        price_per_unit_in_cents:
          description: The price per unit of this item
          format: int32
          type: integer
          minimum: 0
        price_per_unit_in_cents_with_discount:
          description: The discounted price per unit of this item
          format: int32
          type: integer
          minimum: 0
        quantity:
          description: The quantity of this item in the order
          format: int32
          type: integer
          minimum: 1
        sku_code:
          description: The merchant's SKU identifier - required if `sku_id` is not provided
          type: string
        sku_id:
          description: Hive's SKU identifier - required if `sku_code` is not provided
          format: int64
          type: integer
      required:
        - merchant_item_id
        - quantity
      anyOf:
        - required:
            - sku_id
        - required:
            - sku_code
      type: object
      examples:
        - merchant_item_id: '1'
          price_per_unit_in_cents: 1500
          price_per_unit_in_cents_with_discount: 1200
          quantity: 2
          sku_code: SKU-001
          sku_id: 1001
    OrderFulfillmentStatus:
      description: >
        Current fulfillment status of the order within Hive's fulfillment
        process.

        This tracks the order's progress from confirmation through delivery.
        Possible values:

        - waiting_for_picking: Order is confirmed and waiting to be picked in
        the fulfillment center

        - processing: Order is actively being processed (picked/packed) in the
        fulfillment center

        - partially_shipped: Some items from the order have been shipped, but
        others are still pending

        - shipped: All items from the order have been shipped

        - on_hold: Order is temporarily paused (e.g., payment issues, merchant
        request)

        - payment_pending: Order is waiting for payment confirmation

        - cancelled: Order has been cancelled

        - ignored: Order will not be fulfilled (automatically set based on
        external conditions)


        Note: This field is read-only and managed entirely by Hive based on the
        fulfillment process.
      enum:
        - waiting_for_picking
        - processing
        - partially_shipped
        - shipped
        - on_hold
        - payment_pending
        - cancelled
        - ignored
      type: string
      readOnly: true
    OrderPatch:
      description: >
        Schema for updating an existing order. The unique identifiers
        `merchant_order_id` and

        `sales_channel_id` cannot be updated and will be ignored if provided in
        the request body.
      properties:
        carrier_preference:
          description: The preferred carrier to use for delivering this order
          type:
            - string
            - 'null'
        currency:
          $ref: '#/components/schemas/CurrencyCode'
        custom_metadata:
          additionalProperties: true
          description: A JSON object with custom metadata
          type:
            - object
            - 'null'
        customer_order_number:
          description: >-
            The order number which your customer sees. In case this is not the
            same as `merchant_order_id`.
          type:
            - string
            - 'null'
        external_created_at:
          description: >-
            When the order was originally created/placed by the customer. This
            can be different from created_at when doing bulk imports or when
            there's a delay between order placement and API submission.
          format: date-time
          type: string
        financial_status:
          $ref: '#/components/schemas/OrderFinancialStatus'
        items:
          description: List of items in the order (see OrderItem)
          items:
            $ref: '#/components/schemas/OrderItem'
          type: array
        payment_method:
          description: The payment method used for this order
          type: string
        shipping_address:
          $ref: '#/components/schemas/Address'
        tags:
          description: String tags for this order
          items:
            type: string
          type: array
        total_net_refunds_in_cents:
          description: Net refunds in cents (total refunded minus taxes)
          format: int32
          type: integer
          minimum: 0
        total_net_revenue_in_cents:
          description: Net revenue in cents (amount paid minus taxes)
          format: int32
          type: integer
          minimum: 0
        total_price_in_cents:
          description: Total price paid in cents
          format: int32
          type: integer
          minimum: 0
        total_tax_in_cents:
          description: Total tax paid in cents
          format: int32
          type: integer
          minimum: 0
        total_tax_refunds_in_cents:
          description: Total tax in the refunded amount in cents
          format: int32
          type: integer
          minimum: 0
      type: object
      examples:
        - items:
            - merchant_item_id: '1'
              price_per_unit_in_cents: 1500
              quantity: 2
              sku_code: SKU-001
              sku_id: 1001
          shipping_address:
            city: Berlin
            country_code: DE
            first_name: Anna
            line1: Alexanderplatz 1
            postal_code: '10178'
          currency: EUR
          payment_method: credit_card
          tags:
            - priority
            - gift
          total_price_in_cents: 3000
          total_tax_in_cents: 570
          total_net_revenue_in_cents: 2430
          total_net_refunds_in_cents: 0
          total_tax_refunds_in_cents: 0
          custom_metadata:
            gift_message: Happy Birthday!
          customer_order_number: CUST-ORD-2023-01
          carrier_preference: DHL
    Pagination:
      type: object
      properties:
        first_page_url:
          type: string
          description: URL to fetch the first page of results
        limit:
          type: integer
          description: Number of items returned per page
        next_page_url:
          type:
            - string
            - 'null'
          description: >-
            URL to fetch the next page of results. If null, there are no more
            results.
      examples:
        - first_page_url: https://app.hive.app/merchant_api/v2/collection_of_items?limit=20
          limit: 20
          next_page_url: >-
            https://app.hive.app/merchant_api/v2/collection_of_items?limit=20&page=eyJpZCI6MTIzNDU2fQ
    RestockingShipment:
      properties:
        arrived_at:
          description: When the shipment was arrived
          format: date-time
          type:
            - string
            - 'null'
          readOnly: true
        barcode:
          description: The barcode of the shipment
          type:
            - string
            - 'null'
        created_at:
          description: When the shipment was created
          format: date-time
          type: string
          readOnly: true
        delivery_option:
          $ref: '#/components/schemas/RestockingShipmentDeliveryOption'
        estimated_arrival_date:
          description: Estimated arrival date
          format: date
          type:
            - string
            - 'null'
        id:
          description: Hive's unique identifier
          format: int64
          type: integer
          readOnly: true
        po_number:
          description: Purchase order number
          type:
            - string
            - 'null'
        restocking_shipment_items:
          description: A list of items in the shipment. See RestockingShipmentItem.
          items:
            $ref: '#/components/schemas/RestockingShipmentItem'
          type: array
        status:
          $ref: '#/components/schemas/RestockingShipmentStatus'
        supplier_name:
          description: Supplier name
          type:
            - string
            - 'null'
        tracking_code:
          description: Shipment tracking code
          type:
            - string
            - 'null'
        updated_at:
          description: When the shipment was last updated
          format: date-time
          type: string
          readOnly: true
        warehouse_id:
          description: The ID of the Hive destination warehouse
          format: int64
          type: integer
          readOnly: true
      required:
        - id
        - restocking_shipment_items
        - status
        - warehouse_id
      type: object
      examples:
        - id: 98765
          barcode: SHIP-2023-0001
          created_at: '2023-09-15T09:00:00Z'
          delivery_option: courier
          estimated_arrival_date: '2023-09-20'
          po_number: PO-2023-001
          restocking_shipment_items:
            - id: 1
              sku_id: 1001
              sku_code: SKU-001
              announced_quantity: 50
              arrived_quantity: 50
              damaged_quantity: 0
              missing_quantity: 0
              remarks: All items in good condition
              total_cost_in_cents: 50000
          status: arrived
          supplier_name: Acme Supplies
          tracking_code: TRACK-12345
          updated_at: '2023-09-20T10:00:00Z'
          warehouse_id: 2
    RestockingShipmentCreate:
      properties:
        delivery_option:
          $ref: '#/components/schemas/RestockingShipmentDeliveryOption'
        estimated_arrival_date:
          description: Estimated arrival date
          format: date
          type: string
        po_number:
          description: Purchase order number
          type: string
        restocking_shipment_items:
          description: A list of items in the shipment. See RestockingShipmentItem.
          items:
            properties:
              announced_quantity:
                format: int32
                type: integer
                minimum: 1
              remarks:
                type: string
              sku_code:
                description: >-
                  The merchant's SKU identifier - required if `sku_id` is not
                  provided
                type: string
              sku_id:
                description: >-
                  Hive SKU identifier - required if `sku_code` is not provided.
                  If both are provided, `sku_id` will be used.
                format: int64
                type: integer
              total_cost_in_cents:
                format: int32
                type: integer
                minimum: 0
            required:
              - announced_quantity
            anyOf:
              - required:
                  - sku_id
              - required:
                  - sku_code
            type: object
          type: array
        supplier_name:
          description: Supplier name
          type: string
        tracking_code:
          description: Shipment tracking code
          type: string
        warehouse_id:
          description: The ID of the Hive destination warehouse
          format: int64
          type: integer
      required:
        - delivery_option
        - estimated_arrival_date
        - restocking_shipment_items
        - warehouse_id
      type: object
      examples:
        - delivery_option: courier
          estimated_arrival_date: '2023-09-20'
          po_number: PO-2023-001
          restocking_shipment_items:
            - sku_id: 1001
              sku_code: SKU-001
              announced_quantity: 50
              remarks: All items in good condition
              total_cost_in_cents: 50000
          supplier_name: Acme Supplies
          tracking_code: TRACK-12345
          warehouse_id: 2
    RestockingShipmentDeliveryOption:
      description: |
        Delivery option for the restocking shipment. Possible values:
        - courier: Delivered by courier service
        - dropoff: Dropped off at designated location
        - hive_freight: Delivered using Hive freight service
        - postal: Delivered via postal service
      enum:
        - courier
        - dropoff
        - hive_freight
        - postal
      type: string
    RestockingShipmentItem:
      properties:
        announced_quantity:
          description: Quantity of this item in the shipment
          format: int32
          type: integer
          minimum: 0
        arrived_quantity:
          description: Arrived quantity of this item (after shipment is received)
          format: int32
          type: integer
          minimum: 0
        damaged_quantity:
          description: Damaged quantity of this item (after shipment is received)
          format: int32
          type: integer
          minimum: 0
        id:
          description: Hive's unique identifier
          format: int64
          type: integer
        missing_quantity:
          description: Missing quantity of this item (after shipment is received)
          format: int32
          type: integer
          minimum: 0
        remarks:
          description: Free text for remarks
          type:
            - string
            - 'null'
        sku_code:
          description: The merchant's SKU identifier - required if `sku_id` is not provided
          type: string
        sku_id:
          description: Hive SKU identifier - required if `sku_code` is not provided
          format: int64
          type: integer
        total_cost_in_cents:
          description: Cost in cents
          format: int32
          minimum: 0
          type:
            - integer
            - 'null'
      required:
        - arrived_quantity
        - damaged_quantity
        - missing_quantity
        - sku_code
        - sku_id
      type: object
      examples:
        - id: 1
          sku_id: 1001
          sku_code: SKU-001
          announced_quantity: 50
          arrived_quantity: 50
          damaged_quantity: 0
          missing_quantity: 0
          remarks: All items in good condition
          total_cost_in_cents: 50000
    RestockingShipmentStatus:
      description: |
        Restocking shipment status. Possible values:
          - arrived: Hive completed the arrival documentation, checked packing slip, picture of shipment and documents are uploaded
          - cancelled: the restocking shipment is cancelled by merchant
          - created: the restocking shipment is created and not yet shipped
          - processing: the restocking shipment is getting unpacked and its items are getting restocked into storage boxes and pallets
          - received: the restocking shipment is delivered to the fulfillment center, but its content is not verified yet
          - restocked: the restocking shipment is fully processed in the fulfillment center and its items are completely restocked
          - shipped: initial status meaning that restocking shipment is on the way
      enum:
        - arrived
        - cancelled
        - created
        - processing
        - received
        - restocked
        - shipped
      type: string
      readOnly: true
    RestockingShipmentUpdate:
      properties:
        delivery_option:
          $ref: '#/components/schemas/RestockingShipmentDeliveryOption'
        estimated_arrival_date:
          description: Estimated arrival date
          format: date
          type: string
        po_number:
          description: Purchase order number
          type: string
        restocking_shipment_items:
          description: A list of items in the shipment. See RestockingShipmentItem.
          items:
            properties:
              announced_quantity:
                format: int32
                type: integer
                minimum: 1
              remarks:
                type: string
              sku_code:
                description: >-
                  The merchant's SKU identifier - required if `sku_id` is not
                  provided
                type: string
              sku_id:
                description: Hive SKU identifier - required if `sku_code` is not provided
                format: int64
                type: integer
              total_cost_in_cents:
                format: int32
                type: integer
                minimum: 0
            required:
              - announced_quantity
            anyOf:
              - required:
                  - sku_id
              - required:
                  - sku_code
            type: object
          type: array
        supplier_name:
          description: Supplier name
          type: string
        tracking_code:
          description: Shipment tracking code
          type: string
        warehouse_id:
          description: The ID of the Hive destination warehouse
          format: int64
          type: integer
      type: object
      examples:
        - delivery_option: courier
          estimated_arrival_date: '2023-09-20'
          po_number: PO-2023-001
          restocking_shipment_items:
            - sku_id: 1001
              sku_code: SKU-001
              announced_quantity: 50
              remarks: All items in good condition
              total_cost_in_cents: 50000
          supplier_name: Acme Supplies
          tracking_code: TRACK-12345
          warehouse_id: 2
    Return:
      properties:
        announced_items:
          description: >-
            List of items announced by the customer (via the Customer Portal).
            Can be empty if the return is not a Customer Portal return.
          items:
            $ref: '#/components/schemas/ReturnAnnouncedItem'
          type: array
        carrier:
          description: Carrier name
          type:
            - string
            - 'null'
        completed_handling_at:
          description: When the return handling finished
          format: date-time
          type:
            - string
            - 'null'
        created_at:
          description: When the return was created
          format: date-time
          type: string
        handled_items:
          description: >-
            List of items that were actually handled in the FC. Can be empty if
            return items have not been handled in the FC yet.
          items:
            $ref: '#/components/schemas/ReturnHandledItem'
          type: array
        id:
          description: Hive's unique identifier
          format: int64
          type: integer
        order:
          $ref: '#/components/schemas/ReturnOrder'
        photos:
          description: Photos of the returned items
          items:
            $ref: '#/components/schemas/ReturnPhoto'
          type: array
        received_at:
          description: When the return was received
          format: date-time
          type:
            - string
            - 'null'
        return_reason:
          anyOf:
            - $ref: '#/components/schemas/ReturnReason'
            - type: 'null'
        return_reason_type:
          anyOf:
            - $ref: '#/components/schemas/ReturnReasonType'
            - type: 'null'
        started_processing_at:
          description: When processing at the fulfillment center started
          format: date-time
          type:
            - string
            - 'null'
        status:
          $ref: '#/components/schemas/ReturnStatus'
        tracking_code:
          description: Tracking number assigned by the carrier
          type:
            - string
            - 'null'
        tracking_url:
          description: Carrier website showing tracking information
          type:
            - string
            - 'null'
        updated_at:
          format: date-time
          type: string
      required:
        - announced_items
        - created_at
        - id
        - order
        - status
        - updated_at
      type: object
      examples:
        - id: 5555
          announced_items:
            - id: 1
              quantity: 1
              sku:
                id: 1001
                sku_code: SKU-001
              customer_return_reason: Too small
              customer_return_message: The item did not fit.
          carrier: DHL
          completed_handling_at: '2023-10-10T15:00:00Z'
          created_at: '2023-10-08T10:00:00Z'
          handled_items:
            - id: 1
              quantity: 1
              sku:
                id: 1001
                sku_code: SKU-001
              condition: A
              follow_up_action: restock
              photos: []
          order:
            id: 123456
            merchant_order_id: ORD-1001
            customer_order_number: CUST-ORD-2023-01
          photos:
            - id: 1
              image_url: >-
                https://cdn.hive.app/returns/1.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIA4%&X-Amz-Date=20230525T083045Z&X-Amz-Expires=900&X-Amz-SignedHeaders=host&X-Amz-Signature=d8e3
              photo_type: inside
          received_at: '2023-10-09T12:00:00Z'
          return_reason: customer_return
          return_reason_type: active
          started_processing_at: '2023-10-09T13:00:00Z'
          status: arrived
          tracking_code: TRACK-RET-123
          tracking_url: https://dhl.com/track/RET-123
          updated_at: '2023-10-10T15:00:00Z'
    ReturnAnnouncedItem:
      description: Announced return item object
      properties:
        customer_return_message:
          description: Reason details provided by the customer
          type: string
        customer_return_reason:
          description: Reason provided by the customer
          type: string
        id:
          description: Hive's unique identifier
          type: integer
        quantity:
          description: Quantity of items announced
          type: integer
          minimum: 1
        sku:
          $ref: '#/components/schemas/ReturnSku'
      required:
        - id
        - quantity
        - sku
      type: object
      examples:
        - id: 1
          quantity: 1
          sku:
            id: 1001
            sku_code: SKU-001
          customer_return_reason: Too small
          customer_return_message: The item did not fit properly.
    ReturnHandledItem:
      description: Handled return item object
      properties:
        condition:
          $ref: '#/components/schemas/ReturnItemCondition'
        follow_up_action:
          $ref: '#/components/schemas/ReturnItemFollowUpAction'
        id:
          description: Hive's unique identifier
          type: integer
        inventory_batch_id:
          description: >-
            Unique identifier in Hive system of the inventory batch (if present)
            into which returned item is going to be restocked (relevant only
            when follow_up_action = restock)
          type:
            - integer
            - 'null'
        photos:
          description: Photos of the returned item
          items:
            $ref: '#/components/schemas/ReturnHandledItemPhoto'
          type: array
        quantity:
          description: The quantity of items returned for the same SKU
          type: integer
          minimum: 1
        return_item_id:
          description: >-
            Announced return item's unique identifier in Hive system (can be
            blank, e.g. when the return is not a Customer Portal return)
          type:
            - integer
            - 'null'
        sku:
          $ref: '#/components/schemas/ReturnSku'
      required:
        - id
        - quantity
        - sku
      type: object
      examples:
        - id: 1
          quantity: 1
          sku:
            id: 1001
            sku_code: SKU-001
          condition: A
          follow_up_action: restock
          inventory_batch_id: 12345
          return_item_id: 1
          photos:
            - id: 1
              image_url: >-
                https://cdn.hive.app/returns/item_1.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIA4%&X-Amz-Date=20230525T083045Z&X-Amz-Expires=900&X-Amz-SignedHeaders=host&X-Amz-Signature=d8e3
    ReturnHandledItemPhoto:
      description: Photo object for a handled return item
      properties:
        id:
          description: Hive's unique identifier
          type: integer
        image_url:
          description: Publicly accessible URL (for 15 minutes)
          type: string
      required:
        - id
        - image_url
      type: object
      examples:
        - id: 1
          image_url: >-
            https://cdn.hive.app/returns/photos/item_1.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIA4%&X-Amz-Date=20230525T083045Z&X-Amz-Expires=900&X-Amz-SignedHeaders=host&X-Amz-Signature=d8e3
    ReturnOrder:
      description: Details of the associated order
      properties:
        customer_order_number:
          description: Customer's order identifier
          type: string
        id:
          description: Hive's unique order identifier
          type: integer
        merchant_order_id:
          description: Merchant's unique order identifier
          type: string
      required:
        - customer_order_number
        - id
        - merchant_order_id
      type: object
      examples:
        - id: 123456
          merchant_order_id: ORD-1001
          customer_order_number: CUST-ORD-2023-01
    ReturnPhoto:
      description: Photo object for a return
      properties:
        id:
          description: Hive's unique identifier
          type: integer
        image_url:
          description: Publicly accessible URL (for 15 minutes)
          type: string
        photo_type:
          description: Type of photo. Usual values "inside" or "outside"
          type: string
      required:
        - id
        - image_url
        - photo_type
      type: object
      examples:
        - id: 1
          image_url: >-
            https://cdn.hive.app/returns/1.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIA4%&X-Amz-Date=20230525T083045Z&X-Amz-Expires=900&X-Amz-SignedHeaders=host&X-Amz-Signature=d8e3
          photo_type: inside
    ReturnReason:
      description: |
        Reason for the return. Possible values:
        - customer_return: Customer initiated return
        - customs_documents_missing: Missing customs documentation
        - invalid_address: Invalid shipping address
        - not_picked_up: Package was not picked up by customer
        - other: Other reason not specified
        - rejected_by_customer: Customer rejected the delivery
      enum:
        - customer_return
        - customs_documents_missing
        - invalid_address
        - not_picked_up
        - other
        - rejected_by_customer
      type: string
    ReturnReasonType:
      description: >
        Type of return categorization. Possible values:

        - active: Customer return (end-customer actively shipped the return)

        - passive: Carrier return (end-customer never received the parcel -
        shipped back by carrier for reasons like invalid address, not picked up,
        damages, missing customs documents, etc.)
      enum:
        - active
        - passive
      type: string
    ReturnSku:
      description: SKU details for a returned item
      properties:
        id:
          description: Hive's unique SKU identifier
          type: integer
        sku_code:
          description: Merchant's SKU code
          type: string
      required:
        - id
        - sku_code
      type: object
      examples:
        - id: 1001
          sku_code: SKU-001
    ReturnStatus:
      description: |
        Status of the return. Possible values:
        - action_required: Waiting for merchant guidance
        - arrived: Arrived at fulfillment center
        - handling_completed: Return processing completed
        - on_the_way: On the way to fulfillment center
        - processing: Return processing in progress
      enum:
        - action_required
        - arrived
        - handling_completed
        - on_the_way
        - processing
      type: string
      readOnly: true
    SalesChannel:
      properties:
        active:
          description: Whether the sales channel is actively syncing data with Hive
          type: boolean
        created_at:
          description: When the sales channel was created
          format: date-time
          type: string
          readOnly: true
        domain:
          description: The domain of the sales channel
          type: string
        id:
          description: Hive's unique sales channel identifier
          format: int64
          type: integer
          readOnly: true
        is_b2b:
          description: >-
            Whether the sales channel is a B2B sales channel (orders imported as
            B2B by default)
          type: boolean
        name:
          description: The name of the sales channel
          type: string
        reason_for_not_working:
          description: The reason for the sales channel not working
          type:
            - string
            - 'null'
        type:
          description: The type of the sales channel
          type: string
        updated_at:
          description: When the sales channel was last updated
          format: date-time
          type: string
          readOnly: true
        working:
          description: >-
            Whether the sales channel integration is working properly. If false,
            the reason_for_not_working field will be populated.
          type: boolean
      required:
        - active
        - created_at
        - domain
        - id
        - is_b2b
        - name
        - type
        - updated_at
        - working
      type: object
      examples:
        - id: 10
          name: My Shopify Store
          domain: mystore.shopify.com
          type: shopify
          active: true
          is_b2b: false
          working: true
          reason_for_not_working: null
          created_at: '2023-01-15T10:00:00Z'
          updated_at: '2023-10-01T14:30:00Z'
    Shipment:
      properties:
        created_at:
          description: When the shipment was created
          format: date-time
          type: string
          readOnly: true
        delivered_at:
          description: When the shipment was delivered
          format: date-time
          type:
            - string
            - 'null'
          readOnly: true
        delivery_status:
          anyOf:
            - $ref: '#/components/schemas/ShipmentDeliveryStatus'
            - type: 'null'
        id:
          description: The shipment's unique identifier in Hive
          format: int64
          type: integer
          readOnly: true
        items:
          description: Which line items this shipment includes
          items:
            $ref: '#/components/schemas/ShipmentItem'
          type: array
        merchant_order_id:
          description: Related order's unique identifier provided by merchant
          type: string
        order_id:
          description: Related order's unique identifier in Hive
          format: int64
          type: integer
          readOnly: true
        sales_channel_id:
          description: The ID of the sales channel this shipment belongs to
          format: int64
          type: integer
          readOnly: true
        shipment_provider:
          description: Name of the shipment provider/carrier
          type:
            - string
            - 'null'
        shipped_at:
          description: When the shipment was shipped
          format: date-time
          type:
            - string
            - 'null'
          readOnly: true
        shipping_method:
          type:
            - string
            - 'null'
        status:
          $ref: '#/components/schemas/ShipmentStatus'
        tracking_number:
          description: Tracking number assigned by the shipment provider/carrier
          type:
            - string
            - 'null'
        tracking_url:
          description: Shipment provider website showing tracking information
          type:
            - string
            - 'null'
        updated_at:
          description: When the shipment was updated
          format: date-time
          type: string
          readOnly: true
      required:
        - id
        - items
        - order_id
        - sales_channel_id
        - status
      type: object
      examples:
        - id: 789012
          order_id: 123456
          sales_channel_id: 10
          merchant_order_id: ORD-1001
          status: shipped
          delivery_status: in_transit
          shipment_provider: DHL
          shipping_method: Standard
          tracking_number: '1234567890123456'
          tracking_url: https://dhl.com/track/1234567890123456
          created_at: '2023-10-01T12:00:00Z'
          shipped_at: '2023-10-02T08:00:00Z'
          delivered_at: '2023-10-03T14:30:00Z'
          updated_at: '2023-10-02T08:00:00Z'
          items:
            - id: 1
              merchant_item_id: '1'
              quantity: 2
              sku:
                id: 1001
                sku_code: SKU-001
              batches:
                - expiry_date: '2024-12-31'
                  name: BATCH-001
                  quantity: 2
                  tracking_code: TRACK-001
              serial_numbers:
                - serial_number: SN001
                - serial_number: SN002
    ShipmentDeliveryStatus:
      description: >
        Delivery status of the shipment. Possible values:

        - action_required: Unconventional event (e.g. failed delivery, lost
        shipment, address issues)

        - awaiting_customer_pickup: Package is ready for customer pickup

        - delivered: Successfully delivered

        - in_transit: On the way to carrier hub

        - information_transmitted: Information sent to carrier (shipped but no
        carrier updates yet)

        - other: Unknown or other delivery status

        - out_for_delivery: Left carrier hub, being delivered

        - return_initiated: Return process has been initiated

        - returned_to_sender: Carrier initiated return to sender
      enum:
        - action_required
        - awaiting_customer_pickup
        - delivered
        - in_transit
        - information_transmitted
        - other
        - out_for_delivery
        - return_initiated
        - returned_to_sender
      type: string
      readOnly: true
    ShipmentStatus:
      description: >
        Status of the shipment. Possible values:

        - cancelled: Shipment cancelled and will not be fulfilled

        - in_packing: Packing process started

        - in_picking: Picking process started

        - in_shipping: Shipping process started

        - on_hold: On hold (e.g. future fulfillment, address issues,
        insufficient inventory)

        - packed: Items packed and ready for shipping

        - picked: Items picked and ready for packing

        - picking_assigned: Employee assigned to pick items

        - shipped: Shipping label created and left packing station

        - waiting_for_picking: Initial status, awaiting picking
      enum:
        - cancelled
        - in_packing
        - in_picking
        - in_shipping
        - on_hold
        - packed
        - picked
        - picking_assigned
        - shipped
        - waiting_for_picking
      type: string
      readOnly: true
    ShipmentItem:
      properties:
        batches:
          description: Which batches were sent for this line item
          items:
            $ref: '#/components/schemas/ShipmentItemBatch'
          type: array
        id:
          description: The shipment item's unique identifier in Hive
          format: int64
          type: integer
        merchant_item_id:
          description: >-
            The order line item identifier as provided by the merchant. Will be
            null for items added later (e.g. via add-on rules).
          type:
            - string
            - 'null'
        quantity:
          description: Number of SKUs in this line item
          format: int32
          type: integer
        serial_numbers:
          description: Which serial numbers were sent for this line item
          items:
            $ref: '#/components/schemas/ShipmentItemSerialNumber'
          type: array
        sku:
          $ref: '#/components/schemas/ShipmentItemSku'
      required:
        - id
        - quantity
        - sku
      type: object
      examples:
        - id: 1
          merchant_item_id: '1'
          quantity: 2
          sku:
            id: 1001
            sku_code: SKU-001
          batches:
            - expiry_date: '2024-12-31'
              name: BATCH-001
              quantity: 2
              tracking_code: TRACK-001
          serial_numbers:
            - serial_number: SN001
            - serial_number: SN002
    ShipmentItemBatch:
      properties:
        expiry_date:
          description: Expiration date of the batch
          format: date
          type: string
        name:
          description: Name of the batch
          type: string
        quantity:
          description: Number of items taken from this batch
          format: int32
          type: integer
        tracking_code:
          description: Tracking code of the batch
          type: string
      required:
        - expiry_date
        - name
        - quantity
        - tracking_code
      type: object
      examples:
        - expiry_date: '2024-12-31'
          name: BATCH-001
          quantity: 2
          tracking_code: TRACK-001
    ShipmentItemSerialNumber:
      properties:
        serial_number:
          description: The serial number
          type: string
      required:
        - serial_number
      type: object
      examples:
        - serial_number: SN001
    ShipmentItemSku:
      properties:
        id:
          description: Hive unique identifier for the SKU
          format: int64
          type: integer
        sku_code:
          description: SKU identifier as provided by the merchant
          type: string
      required:
        - id
        - sku_code
      type: object
      examples:
        - id: 1001
          sku_code: SKU-001
    Sku:
      properties:
        barcode:
          description: Barcode of the SKU
          type:
            - string
            - 'null'
          minLength: 1
        batch_tracking_enabled:
          description: Whether batch tracking of this SKU is enabled
          type: boolean
        cost_in_cents:
          description: Cost in cents (currency of the shop is implied)
          type:
            - integer
            - 'null'
          minimum: 0
        country_code_of_origin:
          description: >-
            2-letter [ISO
            3166-1](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) code of
            country of origin
          type:
            - string
            - 'null'
          pattern: ^[A-Z]{2}$
        created_at:
          description: When this SKU was created
          format: date-time
          type: string
          readOnly: true
        updated_at:
          description: When this SKU was last updated
          format: date-time
          type: string
          readOnly: true
        dangerous_good:
          description: Sku is a dangerous good
          type: boolean
        fulfilled_by:
          $ref: '#/components/schemas/SkuFulfilledBy'
        h_codes:
          description: Hazardous good H Codes
          items:
            type: string
          type: array
        hazardous_good:
          description: SKU is a hazardous good
          type: boolean
        hs_code:
          description: >-
            The general [Harmonized System (HS)
            code](https://en.wikipedia.org/wiki/Harmonized_System) for the SKU
          type:
            - string
            - 'null'
        id:
          description: Hive unique identifier for this SKU
          format: int64
          type: integer
          readOnly: true
        image_url:
          description: Publicly accessible URL of an image for this SKU
          type:
            - string
            - 'null'
        inventory:
          $ref: '#/components/schemas/SkuInventory'
        inventory_batches:
          description: Current inventory per batch
          items:
            $ref: '#/components/schemas/SkuInventoryBatch'
          type: array
        inventory_per_warehouse:
          description: Current inventory per warehouse
          items:
            $ref: '#/components/schemas/SkuInventoryPerWarehouse'
          type: array
        name:
          description: Name of this SKU
          type: string
        sku_code:
          description: SKU code - visible in the UI
          type: string
        status:
          $ref: '#/components/schemas/SkuStatus'
        un_numbers:
          description: Dangerous good UN Numbers
          items:
            type: string
          type: array
        weight_in_kg:
          description: Weight of SKU in kilograms
          anyOf:
            - type: number
            - type: 'null'
          minimum: 0
      required:
        - batch_tracking_enabled
        - created_at
        - dangerous_good
        - fulfilled_by
        - h_codes
        - hazardous_good
        - id
        - inventory
        - inventory_batches
        - inventory_per_warehouse
        - name
        - sku_code
        - status
        - un_numbers
        - updated_at
        - weight_in_kg
      type: object
      examples:
        - id: 1001
          name: T-Shirt Black M
          sku_code: SKU-001
          barcode: '1234567890123'
          batch_tracking_enabled: false
          cost_in_cents: 800
          country_code_of_origin: DE
          created_at: '2023-09-01T08:00:00Z'
          updated_at: '2023-10-01T14:30:00Z'
          dangerous_good: false
          fulfilled_by: hive
          h_codes: []
          hazardous_good: false
          hs_code: '610910'
          image_url: >-
            https://cdn.hive.app/skus/sku-001.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIA4%&X-Amz-Date=20230525T083045Z&X-Amz-Expires=900&X-Amz-SignedHeaders=host&X-Amz-Signature=d8e3
          inventory:
            available: 90
            reserved: 10
            stocked: 100
          inventory_batches: []
          inventory_per_warehouse:
            - warehouse_id: 2
              available: 45
              reserved: 5
              stocked: 50
          status: active
          un_numbers: []
          weight_in_kg: 0.2
    SkuCreate:
      properties:
        barcode:
          description: The SKU barcode
          type:
            - string
            - 'null'
          minLength: 1
        batch_tracking_enabled:
          description: Enables inventory tracking per batch (defaults to false if omitted)
          type: boolean
        cost_in_cents:
          description: The cost (not price) of this SKU
          type:
            - integer
            - 'null'
          minimum: 0
        country_code_of_origin:
          description: >-
            2-letter [ISO
            3166-1](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) code of
            country of origin
          type:
            - string
            - 'null'
          pattern: ^[A-Z]{2}$
        hs_code:
          description: >-
            [Harmonized System](https://en.wikipedia.org/wiki/Harmonized_System)
            code
          type:
            - string
            - 'null'
        image_url:
          description: Image of the product, must be publicly accessible.
          type:
            - string
            - 'null'
        name:
          description: A human-readable name or title
          type: string
          minLength: 1
        sku_code:
          description: An ID that uniquely identifies this SKU
          type: string
          minLength: 1
        weight_in_kg:
          description: Weight in kilograms
          anyOf:
            - type: number
            - type: 'null'
          minimum: 0
      required:
        - name
        - sku_code
      type: object
      examples:
        - name: T-Shirt Black M
          sku_code: SKU-001
          barcode: '1234567890123'
          batch_tracking_enabled: false
          cost_in_cents: 800
          country_code_of_origin: DE
          hs_code: '610910'
          image_url: https://cdn.hive.app/skus/sku-001.jpg
          weight_in_kg: 0.2
    SkuInventory:
      properties:
        available:
          description: Quantity available for sale (stocked minus reserved)
          type: integer
        reserved:
          description: Quantity reserved/committed for orders
          type: integer
          minimum: 0
        stocked:
          description: Quantity in the warehouse (available plus reserved)
          type: integer
          minimum: 0
      required:
        - available
        - reserved
        - stocked
      type: object
      examples:
        - available: 90
          reserved: 10
          stocked: 100
    SkuInventoryBatch:
      properties:
        expiry_date:
          description: Expiration date of the batch (ISO8601 date, read-only)
          type:
            - string
            - 'null'
          format: date
        id:
          description: Hive unique ID for the batch (read-only)
          type: integer
        name:
          description: Name of the batch (read-only)
          type: string
        stocked_quantities:
          description: >-
            Inventory per warehouse for this batch (see
            SkuInventoryBatchQuantityPerWarehouse) (read-only)
          items:
            $ref: '#/components/schemas/SkuInventoryBatchQuantityPerWarehouse'
          type: array
        tracking_code:
          description: Tracking code (read-only)
          type: string
      required:
        - expiry_date
        - id
        - name
        - stocked_quantities
        - tracking_code
      type: object
      examples:
        - expiry_date: '2024-12-31'
          id: 1
          name: Batch-001
          stocked_quantities:
            - warehouse_id: 2
              stocked: 50
          tracking_code: BATCH-TRACK-001
    SkuInventoryBatchQuantityPerWarehouse:
      properties:
        stocked:
          description: Quantity in the warehouse for this batch in this warehouse
          type: integer
          minimum: 0
        warehouse_id:
          description: Hive's unique warehouse ID
          type: integer
      required:
        - stocked
        - warehouse_id
      type: object
      examples:
        - warehouse_id: 2
          stocked: 50
    SkuInventoryPerWarehouse:
      properties:
        available:
          description: Quantity available for sale (stocked minus reserved)
          type: integer
        reserved:
          description: Quantity reserved/committed for orders
          type: integer
          minimum: 0
        stocked:
          description: Quantity in the warehouse (available plus reserved)
          type: integer
          minimum: 0
        warehouse_id:
          description: Hive's unique warehouse ID
          type: integer
      required:
        - available
        - reserved
        - stocked
        - warehouse_id
      type: object
      examples:
        - warehouse_id: 2
          available: 45
          reserved: 5
          stocked: 50
    SkuPatch:
      properties:
        barcode:
          description: The SKU barcode
          type:
            - string
            - 'null'
          minLength: 1
        batch_tracking_enabled:
          description: Enables inventory tracking per batch (defaults to false if omitted)
          type: boolean
        cost_in_cents:
          description: The cost (not price) of this SKU
          type:
            - integer
            - 'null'
          minimum: 0
        country_code_of_origin:
          description: >-
            2-letter [ISO
            3166-1](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) code of
            country of origin
          type:
            - string
            - 'null'
          pattern: ^[A-Z]{2}$
        hs_code:
          description: >-
            [Harmonized System](https://en.wikipedia.org/wiki/Harmonized_System)
            code
          type:
            - string
            - 'null'
        image_url:
          description: Image of the product, must be publicly accessible.
          type:
            - string
            - 'null'
        name:
          description: A human-readable name or title
          type: string
          minLength: 1
        sku_code:
          description: An ID that uniquely identifies this SKU
          type: string
          minLength: 1
        weight_in_kg:
          description: Weight in kilograms
          anyOf:
            - type: number
            - type: 'null'
          minimum: 0
      type: object
      examples:
        - name: T-Shirt Black M
          sku_code: SKU-001
          barcode: '1234567890123'
          batch_tracking_enabled: false
          cost_in_cents: 800
          country_code_of_origin: DE
          hs_code: '610910'
          image_url: https://cdn.hive.app/skus/sku-001.jpg
          weight_in_kg: 0.2
    Warehouse:
      properties:
        city:
          description: City where the warehouse is located
          readOnly: true
          type: string
        country:
          allOf:
            - $ref: '#/components/schemas/CountryCode'
          readOnly: true
        created_at:
          description: When the warehouse was created
          format: date-time
          type: string
          readOnly: true
        id:
          description: Hive unique ID
          format: int64
          readOnly: true
          type: integer
        name:
          description: Name of the warehouse
          readOnly: true
          type: string
        updated_at:
          description: When the warehouse was last updated
          format: date-time
          type: string
          readOnly: true
      required:
        - id
        - name
        - created_at
        - updated_at
      type: object
      examples:
        - id: 2
          name: BER1
          city: Berlin
          country: DE
          created_at: '2023-01-15T10:00:00Z'
          updated_at: '2023-10-01T14:30:00Z'
    ReturnItemCondition:
      description: |
        Condition of the returned item. Possible values:
        - A: Unused and in original packaging
        - B: Unused with missing/damaged packaging
        - C: Product is used or damaged
      enum:
        - A
        - B
        - C
      type: string
    ReturnItemFollowUpAction:
      description: >
        Action to be performed on the returned item. Those actions are
        pre-selected based on return rules (Hive account manager inserts return
        rules into the system after negotiation with a merchant).

        Possible values:

        - dispose: Dispose of the item

        - restock: Restock the item for sale

        - send_back: Send the item back to the merchant
      enum:
        - dispose
        - restock
        - send_back
      type: string
    SkuFulfilledBy:
      description: |
        Who is fulfilling this SKU. Possible values:
        - hive: Fulfilled by Hive
        - new: Default value for newly imported SKUs
        - other: Fulfilled by another party
      enum:
        - hive
        - new
        - other
      type: string
    SkuStatus:
      description: |
        Status of this SKU. Possible values:
        - active: SKU is active and available for orders
        - deleted: SKU is deleted and no longer available
      enum:
        - active
        - deleted
      type: string
    InventoryTransferOrderStatus:
      description: >
        Status of the inventory transfer order. Possible values:

        - pending: Initial status when the transfer order is created

        - created: The transfer order has been created and is ready for
        processing

        - processing: The transfer order is currently being processed

        - completed: The transfer order has been successfully completed

        - cancelled: The transfer order has been cancelled
      enum:
        - pending
        - created
        - processing
        - completed
        - cancelled
      type: string
      readOnly: true
    CountryCode:
      description: >
        2-letter [ISO 3166-1](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)
        country code.

        Examples: DE, US, FR, NL
      type: string
      pattern: ^[A-Z]{2}$
      examples:
        - DE
    CurrencyCode:
      description: >
        3-letter [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) currency
        code.

        Examples: EUR, USD, GBP, JPY
      type: string
      pattern: ^[A-Z]{3}$
      examples:
        - EUR
    WebhookOrder:
      type: object
      properties:
        event_type:
          description: The type of webhook event
          type: string
          enum:
            - order.status_updated
        event_id:
          description: Unique identifier for this webhook event
          type: string
          format: uuid
        timestamp:
          description: When the event occurred
          type: string
          format: date-time
        data:
          $ref: '#/components/schemas/Order'
      required:
        - event_type
        - event_id
        - timestamp
        - data
      examples:
        - event_type: order.status_updated
          event_id: 123e4567-e89b-12d3-a456-426614174000
          timestamp: '2023-10-01T12:00:00Z'
          data:
            id: 123456
            merchant_order_id: ORD-1001
            sales_channel_id: 10
            fulfillment_status: shipped
            financial_status: paid
            created_at: '2023-10-01T12:00:00Z'
            currency: EUR
            total_price_in_cents: 3000
            total_net_refunds_in_cents: 0
            total_net_revenue_in_cents: 2430
            total_tax_in_cents: 570
            total_tax_refunds_in_cents: 0
            carrier_preference: DHL
            updated_at: '2023-10-01T14:30:00Z'
            items:
              - merchant_item_id: '1'
                quantity: 2
                sku_code: SKU-001
            shipping_address:
              city: Berlin
              country_code: DE
              first_name: Anna
              line1: Alexanderplatz 1
              postal_code: '10178'
    WebhookShipment:
      type: object
      properties:
        event_type:
          description: The type of webhook event
          type: string
          enum:
            - shipment.status_updated
            - shipment.delivery_status_updated
        event_id:
          description: Unique identifier for this webhook event
          type: string
          format: uuid
        timestamp:
          description: When the event occurred
          type: string
          format: date-time
        data:
          $ref: '#/components/schemas/Shipment'
      required:
        - event_type
        - event_id
        - timestamp
        - data
      examples:
        - event_type: shipment.status_updated
          event_id: 123e4567-e89b-12d3-a456-426614174001
          timestamp: '2023-10-01T15:00:00Z'
          data:
            id: 789012
            order_id: 123456
            sales_channel_id: 10
            status: shipped
            items:
              - id: 1
                merchant_item_id: '1'
                quantity: 2
                sku:
                  id: 1001
                  sku_code: SKU-001
                batches:
                  - expiry_date: '2024-12-31'
                    name: BATCH-001
                    quantity: 2
                    tracking_code: TRACK-001
                serial_numbers:
                  - serial_number: SN001
                  - serial_number: SN002
    WebhookRestockingShipment:
      type: object
      properties:
        event_type:
          description: The type of webhook event
          type: string
          enum:
            - restocking_shipment.status_updated
        event_id:
          description: Unique identifier for this webhook event
          type: string
          format: uuid
        timestamp:
          description: When the event occurred
          type: string
          format: date-time
        data:
          $ref: '#/components/schemas/RestockingShipment'
      required:
        - event_type
        - event_id
        - timestamp
        - data
      examples:
        - event_type: restocking_shipment.status_updated
          event_id: 123e4567-e89b-12d3-a456-426614174003
          timestamp: '2023-10-01T16:00:00Z'
          data:
            id: 98765
            status: arrived
            warehouse_id: 2
            restocking_shipment_items:
              - id: 1
                sku_id: 1001
                sku_code: SKU-001
                announced_quantity: 50
                arrived_quantity: 50
                damaged_quantity: 0
                missing_quantity: 0
    WebhookReturn:
      type: object
      properties:
        event_type:
          description: The type of webhook event
          type: string
          enum:
            - return.status_updated
        event_id:
          description: Unique identifier for this webhook event
          type: string
          format: uuid
        timestamp:
          description: When the event occurred
          type: string
          format: date-time
        data:
          $ref: '#/components/schemas/Return'
      required:
        - event_type
        - event_id
        - timestamp
        - data
      examples:
        - event_type: return.status_updated
          event_id: 123e4567-e89b-12d3-a456-426614174002
          timestamp: '2023-10-01T18:00:00Z'
          data:
            id: 5555
            status: arrived
            created_at: '2023-10-01T18:00:00Z'
            updated_at: '2023-10-01T18:00:00Z'
            announced_items:
              - id: 1
                quantity: 1
                sku:
                  id: 1001
                  sku_code: SKU-001
            order:
              id: 123456
              merchant_order_id: ORD-1001
              customer_order_number: CUST-ORD-2023-01
    WebhookInventoryTransferOrder:
      type: object
      properties:
        event_type:
          description: The type of webhook event
          type: string
          enum:
            - inventory_transfer_order.status_updated
        event_id:
          description: Unique identifier for this webhook event
          type: string
          format: uuid
        timestamp:
          description: When the event occurred
          type: string
          format: date-time
        data:
          $ref: '#/components/schemas/InventoryTransferOrder'
      required:
        - event_type
        - event_id
        - timestamp
        - data
      examples:
        - event_type: inventory_transfer_order.status_updated
          event_id: 123e4567-e89b-12d3-a456-426614174004
          timestamp: '2023-10-01T19:00:00Z'
          data:
            id: 123456
            status: completed
            created_at: '2023-10-01T19:00:00Z'
            completed_at: '2023-10-01T20:00:00Z'
            origin_id: 4
            destination_id: 2
            updated_at: '2023-10-01T20:00:00Z'
            order:
              id: 1195780
              status: processing
            order_notes: ''
            documents: []
            restocking_shipments: []
            shipments: []
            items:
              - id: 427
                quantity: 50
                sku_id: 1001
                sku_code: SKU-001
  securitySchemes:
    BearerAuth:
      bearerFormat: token
      description: |
        A merchant-scoped API token used to authenticate all API requests.

        This token provides access to all sales channels owned by the merchant.
      scheme: bearer
      type: http
